<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 1.5.5">
<meta name="author" content="2019-08-08 13:15:33 CEST">
<title>N4JS Design Specification</title>
<link rel="stylesheet" href="styles/spec.min.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css">
<!-- ************* docinfo ******************************************************************* -->


<!-- ************* Favicon ************-->
<link rel="icon" href="images/favicon.ico" />

<!-- ************* Back-to-top JQuery ************* -->
<script src="https://code.jquery.com/jquery-1.12.4.js"></script>
<script src="https://code.jquery.com/ui/1.12.0/jquery-ui.js"></script>


<link href="styles/prism.min.css" rel="stylesheet" />
<script type="text/javascript" async
  src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js?config=TeX-MML-AM_CHTML">
</script>

<!-- ************* Styles ************* -->
<link rel="stylesheet" type="text/css" href="styles/n4jsspec-adoc.css">


<!-- ****************** NavBar ****************** -->
<div id="menubar">
	<div class="banner">
        <a href="https://www.eclipse.org/n4js/#"><img id="logo" src="images/n4js-logo.png" alt="Eclipse N4JS"></a>
    </div>
<ul>
  <li><a href="index.html">Index</a></li>
</ul>
</div>
<!-- ************* docinfo ******************************************************************* -->
<style>
      .admonitionblock td.icon .icon-todo:before{content:"\f249";color:#f4ee42}
    </style>
</head>
<body class="book toc2 toc-left">
<div id="header">
<h1>N4JS Design Specification</h1>
<div class="details">
<span id="author" class="author">2019-08-08 13:15:33 CEST</span><br>
<span id="revnumber">version 0.9</span>
</div>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="introduction.html#_introduction">1. Introduction</a>
<ul class="sectlevel2">
<li><a href="introduction.html#notation">1.1. Notation</a></li>
<li><a href="introduction.html#sec:IDE_Overview">1.2. IDE Components</a>
<ul class="sectlevel3">
<li><a href="introduction.html#sec:Naming_Conventions">1.2.1. Naming Conventions</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="eclipse_setup.html#_eclipse-setup">2. Eclipse Setup</a>
<ul class="sectlevel2">
<li><a href="eclipse_setup.html#_system-requirements">2.1. System Requirements</a></li>
<li><a href="eclipse_setup.html#_contribute">2.2. Contribute</a>
<ul class="sectlevel3">
<li><a href="eclipse_setup.html#_eclipse-installer">2.2.1. Eclipse Installer</a>
<ul class="sectlevel4">
<li><a href="eclipse_setup.html#_changing-the-setup-script">2.2.1.1. Changing the Setup Script</a></li>
</ul>
</li>
<li><a href="eclipse_setup.html#_manual-ide-configuration">2.2.2. Manual IDE Configuration</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="release_engineering.html#_release-engineering">3. Release Engineering</a>
<ul class="sectlevel2">
<li><a href="release_engineering.html#_nightly-build-on-eclipse-infrastructure">3.1. Nightly build on Eclipse infrastructure</a></li>
<li><a href="release_engineering.html#_build-the-n4js-ide-from-command-line">3.2. Build the N4JS IDE from command line</a>
<ul class="sectlevel3">
<li><a href="release_engineering.html#_publish-maven-tooling-code-org-eclipse-n4js-releng-util-code">3.2.1. Publish maven-tooling <code>org.eclipse.n4js.releng.util</code></a></li>
<li><a href="release_engineering.html#sec:test-verdaccio">3.2.2. Test Verdaccio containing n4js-libs</a></li>
<li><a href="release_engineering.html#_generation-of-eclipse-help-for-spec-and-design-document">3.2.3. Generation of Eclipse help for spec and design document</a></li>
</ul>
</li>
<li><a href="release_engineering.html#_updating-frameworks-and-dependencies">3.3. Updating frameworks and dependencies</a>
<ul class="sectlevel3">
<li><a href="release_engineering.html#_update-of-eclipse-emf-xtext-etc">3.3.1. Update of Eclipse, EMF, Xtext, etc.</a></li>
<li><a href="release_engineering.html#_update-of-the-embedded-jre">3.3.2. Update of the embedded JRE</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="tips_and_tricks.html#_tips-and-tricks">4. Tips and Tricks</a>
<ul class="sectlevel2">
<li><a href="tips_and_tricks.html#_naming">4.1. Naming</a></li>
<li><a href="tips_and_tricks.html#_logging">4.2. Logging</a></li>
<li><a href="tips_and_tricks.html#_cancellation-handling">4.3. Cancellation Handling</a></li>
<li><a href="tips_and_tricks.html#_caching">4.4. Caching</a></li>
<li><a href="tips_and_tricks.html#_dependency-injection">4.5. Dependency Injection</a></li>
<li><a href="tips_and_tricks.html#_miscellaneous">4.6. Miscellaneous</a></li>
</ul>
</li>
<li><a href="parser.html#_parser">5. Parser</a>
<ul class="sectlevel2">
<li><a href="parser.html#sec:Parser_Overview">5.1. Overview</a></li>
<li><a href="parser.html#sec:N4JS_Parser">5.2. N4JS Parser</a></li>
<li><a href="parser.html#sec:Parser_Generation_Post_Processing">5.3. Parser Generation Post-Processing</a>
<ul class="sectlevel3">
<li><a href="parser.html#sec:Automatic_Semicolon_Insertion">5.3.1. Automatic Semicolon Insertion</a>
<ul class="sectlevel4">
<li><a href="parser.html#sec:Injected_code_in_the_Antlr_grammar_file">5.3.1.1. Injected code in the Antlr grammar file</a></li>
<li><a href="parser.html#sec:Customized_error_recovery">5.3.1.2. Customized error recovery</a></li>
</ul>
</li>
<li><a href="parser.html#sec:_No_line_terminator_allowed_here__handling">5.3.2. Async and <code>No line terminator allowed here</code> Handling</a></li>
<li><a href="parser.html#sec:Regular_Expression">5.3.3. Regular Expression</a></li>
<li><a href="parser.html#sec:Unicode">5.3.4. Unicode</a></li>
<li><a href="parser.html#sec:Literals">5.3.5. Literals</a></li>
</ul>
</li>
<li><a href="parser.html#sec:Modifiers">5.4. Modifiers</a></li>
<li><a href="parser.html#sec:Conflict_Resolutions">5.5. Conflict Resolutions</a>
<ul class="sectlevel3">
<li><a href="parser.html#sec:Reserved_Keywords_vs__Identifier_Names">5.5.1. Reserved Keywords vs. Identifier Names</a></li>
<li><a href="parser.html#sec:Operators_and_Generics">5.5.2. Operators and Generics</a></li>
</ul>
</li>
<li><a href="parser.html#sec:Content_Assist_Parser">5.6. Content-Assist Parser</a></li>
</ul>
</li>
<li><a href="type_system.html#_type-system">6. Type System</a>
<ul class="sectlevel2">
<li><a href="type_system.html#sec:Type_Model_and_Grammar">6.1. Type Model and Grammar</a>
<ul class="sectlevel3">
<li><a href="type_system.html#sec:Type_Model_Overview">6.1.1. Type Model Overview</a></li>
<li><a href="type_system.html#sec:Built_in_Types">6.1.2. Built-in and Primitive Types</a></li>
<li><a href="type_system.html#sec:Type_Model_DSL">6.1.3. Type Model DSL</a></li>
</ul>
</li>
<li><a href="type_system.html#sec:Type_System_Implementation">6.2. Type System Implementation</a></li>
<li><a href="type_system.html#sec:Type_Inference_combined_with_AST_Traversal">6.3. Type Inference of AST</a>
<ul class="sectlevel3">
<li><a href="type_system.html#sec:Type_Inference_combined_with_AST_Traversal__Background">6.3.1. Background</a></li>
<li><a href="type_system.html#sec:Triggering_Type_Inference_of_AST">6.3.2. Triggering</a></li>
<li><a href="type_system.html#sec:Traversal_Order_During_Type_Inference_of_AST">6.3.3. Traversal Order</a></li>
<li><a href="type_system.html#sec:Cross_References_During_Type_Inference_of_AST">6.3.4. Cross-References</a></li>
<li><a href="type_system.html#sec:Function_Accessor_Bodies_During_Type_Inference_of_AST">6.3.5. Function/Accessor Bodies</a></li>
<li><a href="type_system.html#sec:Poly_Expressions_During_Type_Inference_of_AST">6.3.6. Poly Expressions</a></li>
<li><a href="type_system.html#sec:Constraint_Solver_used_During_Type_Inference_of_AST">6.3.7. Constraint Solver</a></li>
<li><a href="type_system.html#sec:Type_Guards_During_Type_Inference_of_AST">6.3.8. Type Guards</a></li>
</ul>
</li>
<li><a href="type_system.html#sec:Structural_Typing">6.4. Structural Typing</a></li>
</ul>
</li>
<li><a href="type_index.html#_type-index">7. Type Index</a>
<ul class="sectlevel2">
<li><a href="type_index.html#sec:Type_Index_Design_Rationale">7.1. Design Rationale</a>
<ul class="sectlevel3">
<li><a href="type_index.html#sec:Getting_the_Xtext_Index_Content_IResourceDescriptions">7.1.1. Getting the Xtext Index (<code>IResourceDescriptions</code>) Content</a></li>
</ul>
</li>
<li><a href="type_index.html#sec:Design_Overview">7.2. Design Overview</a></li>
<li><a href="type_index.html#sec:N4JS_Resource_Load_States">7.3. N4JS Resource Load States</a></li>
<li><a href="type_index.html#sec:Type_Builder">7.4. Types Builder</a>
<ul class="sectlevel3">
<li><a href="type_index.html#sec:Type_Inference_not_allowed_in_Type_Builder">7.4.1. Type Inference not allowed in Types Builder</a></li>
<li><a href="type_index.html#sec:ComputedTypeReferences">7.4.2. Deferred Type References</a></li>
<li><a href="type_index.html#sec:Use_cases_of_ComputedTypeRef">7.4.3. Use cases of DeferredTypeRef</a></li>
</ul>
</li>
<li><a href="type_index.html#sec:Incremental_Builder_Overview">7.5. Incremental Builder (Overview)</a>
<ul class="sectlevel3">
<li><a href="type_index.html#sec:Incremental_Builder_Overview__XtextBuilder">7.5.1. XtextBuilder</a></li>
<li><a href="type_index.html#sec:Incremental_Builder_Overview__IBuilderState">7.5.2. IBuilderState</a>
<ul class="sectlevel4">
<li><a href="type_index.html#copy-and-update-xtext-index">7.5.2.1. Copy and Update Xtext Index</a></li>
<li><a href="type_index.html#build-state-setup-phase">7.5.2.2. Build State Setup Phase</a></li>
<li><a href="type_index.html#process-queued-uris">7.5.2.3. Process Queued URIs</a></li>
<li><a href="type_index.html#queueing-affected-resources">7.5.2.4. Queueing Affected Resources</a></li>
</ul>
</li>
<li><a href="type_index.html#sec:Incremental_Builder_Overview__Example">7.5.3. Example</a></li>
</ul>
</li>
<li><a href="type_index.html#dirty-state-handling">7.6. Dirty state handling</a>
<ul class="sectlevel3">
<li><a href="type_index.html#use-case-restoring-types-from-user-data">7.6.1. Use case: Restoring types from user data</a></li>
<li><a href="type_index.html#use-case-updating-the-xtext-index">7.6.2. Use case: Updating the Xtext index</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="project_model.html#_project-model">8. Project Model</a>
<ul class="sectlevel2">
<li><a href="project_model.html#sec:Package_json">8.1. Package.json File</a></li>
<li><a href="project_model.html#_accessing-project-information">8.2. Accessing Project Information</a>
<ul class="sectlevel3">
<li><a href="project_model.html#sec:IN4JSCore">8.2.1. IN4JSCore</a></li>
<li><a href="project_model.html#sec:N4JSModel">8.2.2. N4JSModel</a></li>
<li><a href="project_model.html#sec:N4JSWorkspace">8.2.3. N4JSWorkspace</a></li>
<li><a href="project_model.html#sec:N4JSProject">8.2.4. N4JSProject</a></li>
<li><a href="project_model.html#sec:SourceContainer">8.2.5. SourceContainer</a></li>
<li><a href="project_model.html#sec:N4JSProjectsStateHelper">8.2.6. N4JSProjectsStateHelper</a></li>
</ul>
</li>
<li><a href="project_model.html#sec:Caching">8.3. Caching</a>
<ul class="sectlevel3">
<li><a href="project_model.html#_caching-of-externallibraryworkspace">8.3.1. Caching of ExternalLibraryWorkspace</a></li>
<li><a href="project_model.html#_caching-of-n4jsprojectsstatehelper">8.3.2. Caching of N4JSProjectsStateHelper</a></li>
</ul>
</li>
<li><a href="project_model.html#sec:WildcardPathFilter">8.4. WildcardPathFilter</a></li>
<li><a href="project_model.html#sec:ProjectUtils">8.5. ProjectUtils</a></li>
</ul>
</li>
<li><a href="binding.html#_binding">9. Binding</a>
<ul class="sectlevel2">
<li><a href="binding.html#sec:Binding_Design_Rationale">9.1. Design Rationale</a></li>
<li><a href="binding.html#sec:Binding_to_Members">9.2. Binding to Members</a></li>
<li><a href="binding.html#sec:Binding_Getter_Setter">9.3. Getter / Setter Binding</a></li>
<li><a href="binding.html#chap:Statics">9.4. Static Member Binding</a></li>
<li><a href="binding.html#sec:Binding_Enumeration">9.5. Enumeration Literals Binding</a></li>
<li><a href="binding.html#sec:Accessibility_of_types_and_members">9.6. Accessibility of types and members</a></li>
<li><a href="binding.html#sec:Member_Scope_Example">9.7. Member Scope Example</a></li>
<li><a href="binding.html#sec:Scoping_for_Members_of_Composed_Type_Explained">9.8. Scoping for Members of Composed Type (Union/Intersection) Example</a></li>
<li><a href="binding.html#sec:Binding_of_Structurally_References_Types">9.9. Structurally References Types</a></li>
<li><a href="binding.html#sec:Building">9.10. Building</a>
<ul class="sectlevel3">
<li><a href="binding.html#sec:Build_Phases">9.10.1. Build Phases</a></li>
<li><a href="binding.html#sec:Build_Scenarios">9.10.2. Build Scenarios</a></li>
<li><a href="binding.html#sec:Lazy_linking_problem">9.10.3. Lazy linking problem</a></li>
</ul>
</li>
<li><a href="binding.html#sec:Proxies_and_Proxy_Resolution">9.11. Proxies and Proxy Resolution (Overview)</a>
<ul class="sectlevel3">
<li><a href="binding.html#xtexts-lazy-linking-proxies">9.11.1. Xtext’s Lazy Linking Proxies</a></li>
<li><a href="binding.html#standard-emf-proxies">9.11.2. Standard EMF Proxies</a></li>
<li><a href="binding.html#_how-is-proxy-resolution-triggered">9.11.3. How is Proxy Resolution Triggered?</a></li>
<li><a href="binding.html#_when-is-proxy-resolution-allowed">9.11.4. When is Proxy Resolution Allowed?</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="validation.html#_validation">10. Validation</a>
<ul class="sectlevel2">
<li><a href="validation.html#sec:validation_overview">10.1. Validation overview</a></li>
<li><a href="validation.html#sec:validation_control_flow">10.2. Validation control flow</a></li>
<li><a href="validation.html#sec:validation_issue_ids">10.3. Issue IDs and Messages</a></li>
<li><a href="validation.html#sec:validation_usage_patterns">10.4. Usage Pattern</a></li>
<li><a href="validation.html#sec:validation_links">10.5. Links</a></li>
</ul>
</li>
<li><a href="references.html#_references">11. References</a>
<ul class="sectlevel2">
<li><a href="references.html#sec:usecases">11.1. Use cases</a></li>
<li><a href="references.html#sec:calculation_algorithm">11.2. Calculation algorithm</a>
<ul class="sectlevel3">
<li><a href="references.html#sec:Xtext_default_implementation">11.2.1. Xtext default implementation</a></li>
<li><a href="references.html#sec:N4_implementation">11.2.2. N4JS implementation</a></li>
</ul>
</li>
<li><a href="references.html#sec:PerformanceOfDependencyCalculation">11.3. Performance Of Dependency Calculation</a></li>
<li><a href="references.html#sec:kinds_of_references">11.4. Kinds of references</a>
<ul class="sectlevel3">
<li><a href="references.html#sec:Cross_References_to_be_ignored">11.4.1. Cross References to be ignored</a></li>
<li><a href="references.html#sec:Cross_References_to_be_handled">11.4.2. Cross References to be handled</a></li>
</ul>
</li>
<li><a href="references.html#sec:transitive_dependencies">11.5. Transitive dependencies</a></li>
<li><a href="references.html#sec:find-references">11.6. Find references</a>
<ul class="sectlevel3">
<li><a href="references.html#_background">11.6.1. Background</a></li>
<li><a href="references.html#_how-find-references-work">11.6.2. How Find References Work</a>
<ul class="sectlevel4">
<li><a href="references.html#_step-1-convert-cursor-position-to-declared-element">11.6.2.1. Step 1: Convert Cursor Position to Declared Element</a></li>
<li><a href="references.html#_step-2-convert-declared-element-to-target-uris">11.6.2.2. Step 2: Convert Declared Element to Target URIs</a></li>
<li><a href="references.html#_step-3-filter-potential-resources">11.6.2.3. Step 3: Filter Potential Resources</a></li>
<li><a href="references.html#_step-4-search-references-in-resource">11.6.2.4. Step 4: Search References in Resource</a></li>
<li><a href="references.html#_limitations-and-possible-enhancements">11.6.2.5. Limitations and Possible Enhancements</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="compilation.html#_compilation">12. Compilation</a>
<ul class="sectlevel2">
<li><a href="compilation.html#chap:compilation">12.1. Introduction</a>
<ul class="sectlevel3">
<li><a href="compilation.html#sec:general_design_rationals">12.1.1. General design rationals</a>
<ul class="sectlevel4">
<li><a href="compilation.html#sec:logging_and_error_reporting">12.1.1.1. Logging and error reporting</a></li>
<li><a href="compilation.html#sec:progress_monitor">12.1.1.2. Progress monitor</a></li>
</ul>
</li>
<li><a href="compilation.html#sec:Xtext_Integration">12.1.2. Xtext Integration</a>
<ul class="sectlevel4">
<li><a href="compilation.html#sec:xtext_default_behaviour">12.1.2.1. Xtext default behaviour</a></li>
<li><a href="compilation.html#sec:n4js_requirements">12.1.2.2. N4JS requirements</a></li>
<li><a href="compilation.html#sec:compiler_discovery_in_ui">12.1.2.3. Compiler discovery in UI</a></li>
<li><a href="compilation.html#sec:compiler_discovery_in_headless">12.1.2.4. Compiler discovery in headless</a></li>
<li><a href="compilation.html#sec:general_generator_implementation">12.1.2.5. General generator implementation</a></li>
<li><a href="compilation.html#sec:general_generator_activation">12.1.2.6. General generator activation</a></li>
</ul>
</li>
<li><a href="compilation.html#sec:Overview_of_Input_Models">12.1.3. Overview of the Input Models</a></li>
</ul>
</li>
<li><a href="compilation.html#sec:Core_Generator">12.2. Generators</a>
<ul class="sectlevel3">
<li><a href="compilation.html#sec:Compiler_Components">12.2.1. Generator Components</a></li>
<li><a href="compilation.html#sec:Generator_architecture">12.2.2. Generator architecture</a></li>
<li><a href="compilation.html#sec:Unified_Compiler_Configuration">12.2.3. Unified Compiler Configuration</a></li>
</ul>
</li>
<li><a href="compilation.html#sec:Transpilers">12.3. Transpilers</a>
<ul class="sectlevel3">
<li><a href="compilation.html#sec:Phases">12.3.1. Overview</a></li>
<li><a href="compilation.html#relation-between-ast-and-im">12.3.2. Relation between AST and IM</a></li>
<li><a href="compilation.html#implementation-overview">12.3.3. Implementation Overview</a></li>
<li><a href="compilation.html#sec:Guidelines_for_Implementing_Transformations">12.3.4. Guidelines for Implementing Transformations</a></li>
<li><a href="compilation.html#symbol-table-in-the-im">12.3.5. Symbol Table in the IM</a></li>
</ul>
</li>
<li><a href="compilation.html#sec:N4JS_to_EcmaScript_Transpiler">12.4. N4JS-to-EcmaScript Transpiler</a>
<ul class="sectlevel3">
<li><a href="compilation.html#sec:Overview_of_Transformations">12.4.1. Overview of Transformations</a></li>
<li><a href="compilation.html#sec:Transpiling_members">12.4.2. Transpiling members</a>
<ul class="sectlevel4">
<li><a href="compilation.html#sec:Transpiling_members__Delegating_members">12.4.2.1. Techniques for special member handling</a></li>
<li><a href="compilation.html#sec:Transpiling_members__Partial_shadowing_of_getter_setter_pairs">12.4.2.2. Partial shadowing</a></li>
<li><a href="compilation.html#sec:Transpiling_members__Consuming_or_inheriting_members_of_an_interface">12.4.2.3. Consuming or inheriting members of an interface</a></li>
<li><a href="compilation.html#sec:Transpiling_members__Static_polyfill">12.4.2.4. Static polyfill</a></li>
<li><a href="compilation.html#sec:Transpiling_members__API_implementation_stubs">12.4.2.5. API / implementation stubs</a></li>
</ul>
</li>
<li><a href="compilation.html#sec:Support_for_incomplete_API_implementation_testing_in_the_N4JS_to_EcmaScript_5_Transpiler">12.4.3. Support for incomplete API implementation testing</a>
<ul class="sectlevel4">
<li><a href="compilation.html#sec:Modifications_in_Impl_projects">12.4.3.1. Modifications in Impl projects</a></li>
<li><a href="compilation.html#sec:Implementation_of_stub_generation">12.4.3.2. Implementation of stub-generation</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="compilation.html#sec:n4jsc_Headless_Compiler_Interface">12.5. n4jsc Headless Compiler Interface</a>
<ul class="sectlevel3">
<li><a href="compilation.html#sec:building_the_headless_compiler">12.5.1. building the headless compiler</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="execution.html#_execution">13. Execution</a>
<ul class="sectlevel2">
<li><a href="execution.html#sec:N4JS_Project_Execution_And_Linking_Model">13.1. N4JS Project Execution And Linking Model</a>
<ul class="sectlevel3">
<li><a href="execution.html#subsec:N4JS_Execution_With_NodeJS">13.1.1. N4JS Execution With NodeJS</a></li>
</ul>
</li>
<li><a href="execution.html#sec:N4JS_Execution_And_Linking_File">13.2. N4JS Execution And Linking File</a>
<ul class="sectlevel3">
<li><a href="execution.html#subsec:NodeJS_Specific_ELF">13.2.1. NodeJS Specific ELF</a></li>
</ul>
</li>
<li><a href="execution.html#sec:Runners-execution">13.3. Runners</a>
<ul class="sectlevel3">
<li><a href="execution.html#subsec:N4_Runtime_Environments_Convention">13.3.1. N4 Runtime Environments Convention</a></li>
<li><a href="execution.html#subsec:Passing_Information_from_IDE_to_Execution_Code_in_Runtime_Environment">13.3.2. Passing Information from IDE to Execution Code in Runtime Environment</a></li>
<li><a href="execution.html#subsec:Runners_Design">13.3.3. Runners Design</a></li>
</ul>
</li>
<li><a href="execution.html#sec:Legacy_Execution_Engine">13.4. Legacy Execution Engine</a></li>
<li><a href="execution.html#sec:Design">13.5. Design</a>
<ul class="sectlevel3">
<li><a href="execution.html#sec:Usage_Outside_N4JSIDE">13.5.1. Usage Outside N4JSIDE</a>
<ul class="sectlevel4">
<li><a href="execution.html#sec:Use_Node_with_Maven">13.5.1.1. Use Node with Maven</a></li>
</ul>
</li>
<li><a href="execution.html#sec:Usage_Inside_N4JSIDE">13.5.2. Usage Inside N4JSIDE</a></li>
</ul>
</li>
<li><a href="execution.html#sec:Runtime_Injection">13.6. Runtime Injection</a>
<ul class="sectlevel3">
<li><a href="execution.html#sec:Running_String_Code">13.6.1. Running String Code</a></li>
<li><a href="execution.html#sec:Running_File_Code">13.6.2. Running File Code</a></li>
<li><a href="execution.html#sec:Injection_Code_Example">13.6.3. Injection Code Example</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="tests.html#_tests">14. Tests</a>
<ul class="sectlevel2">
<li><a href="tests.html#sec:Performance_Tests">14.1. Performance Tests</a>
<ul class="sectlevel3">
<li><a href="tests.html#sec:Synthetic_Performance_Tests">14.1.1. Synthetic Performance Tests</a>
<ul class="sectlevel4">
<li><a href="tests.html#sec:Design_of_Generator">14.1.1.1. Design of Generator</a></li>
<li><a href="tests.html#sec:Design_of_Performance_Test_Execution">14.1.1.2. Design of Performance Test Configuration and Execution</a></li>
<li><a href="tests.html#sec:JUnit_Configuration">14.1.1.3. JUnit Configuration</a></li>
<li><a href="tests.html#sec:JUnitBenchmark_Test_Configuration">14.1.1.4. JUnitBenchmark Test Configuration</a></li>
<li><a href="tests.html#sec:JUnitBenchmark_Report_Configuration">14.1.1.5. JUnitBenchmark Report Configuration</a></li>
<li><a href="tests.html#sec:JUnitBenchmark_Run_Configuration">14.1.1.6. JUnitBenchmark Run Configuration</a></li>
<li><a href="tests.html#sec:JUnitBenchmark_Example">14.1.1.7. JUnitBenchmark Example</a></li>
<li><a href="tests.html#sec:Note_on_Jenkins_Job">14.1.1.8. Note on Jenkins Job</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="tests.html#sec:ECMA_Tests">14.2. ECMA Tests</a>
<ul class="sectlevel3">
<li><a href="tests.html#sec:Grammar_Tests">14.2.1. Grammar Tests</a>
<ul class="sectlevel4">
<li><a href="tests.html#sec:Negative_Tests">14.2.1.1. Negative Tests</a></li>
<li><a href="tests.html#sec:Test_Exclusion">14.2.1.2. Test Exclusion</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="tests.html#sec:Integration_Tests">14.3. Integration Tests</a></li>
<li><a href="tests.html#sec:Test_Helpers">14.4. Test Helpers</a>
<ul class="sectlevel3">
<li><a href="tests.html#sec:Parameterized_N4JS_Tests">14.4.1. Parameterized N4JS tests</a>
<ul class="sectlevel4">
<li><a href="tests.html#sec:ParameterizedXtextRunner">14.4.1.1. ParameterizedXtextRunner</a></li>
<li><a href="tests.html#sec:TestCodeProvider">14.4.1.2. TestCodeProvider</a></li>
<li><a href="tests.html#sec:Example_Of_Parameterized_Parser_Test">14.4.1.3. Example of parameterized parser test</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="tests.html#sec:Issue_Suppression">14.5. Issue Suppression</a></li>
<li><a href="tests.html#sec:Xpect_Tests">14.6. Xpect Tests</a>
<ul class="sectlevel3">
<li><a href="tests.html#sec:Xpect_Test_Setup">14.6.1. Xpect Test Setup</a></li>
<li><a href="tests.html#sec:Xpect_Issue_Suppression">14.6.2. Xpect Issue Suppression</a></li>
<li><a href="tests.html#sec:Xpect_Provided_Test_Methods">14.6.3. Xpect Provided Test Methods</a>
<ul class="sectlevel4">
<li><a href="tests.html#errors">14.6.3.1. errors</a></li>
<li><a href="tests.html#warnings">14.6.3.2. warnings</a></li>
</ul>
</li>
<li><a href="tests.html#sec:N4JS_Specific_Xpect_Test_Methods">14.6.4. N4JS Specific Xpect Test Methods</a>
<ul class="sectlevel4">
<li><a href="tests.html#sec:XPECT_noerrors">14.6.4.1. noerrors and nowarnings</a></li>
<li><a href="tests.html#sec:XPECT_scope">14.6.4.2. scope</a></li>
<li><a href="tests.html#sec:XPECT_scopeWithPosition">14.6.4.3. scopeWithPosition</a></li>
<li><a href="tests.html#sec:XPECT_scopeWithResource">14.6.4.4. scopeWithResource</a></li>
<li><a href="tests.html#sec:XPECT_binding">14.6.4.5. binding</a></li>
<li><a href="tests.html#sec:XPECT_linkedPathname">14.6.4.6. linkedPathname</a></li>
<li><a href="tests.html#sec:XPECT_type_of">14.6.4.7. type of</a></li>
<li><a href="tests.html#sec:XPECT_expectedType">14.6.4.8. expectedType</a></li>
<li><a href="tests.html#sec:XPECT_elementKeyword">14.6.4.9. elementKeyword</a></li>
<li><a href="tests.html#sec:XPECT_accessModifier">14.6.4.10. accessModifier</a></li>
<li><a href="tests.html#sec:XPECT_compileResult">14.6.4.11. compileResult</a></li>
<li><a href="tests.html#sec:XPECT_output">14.6.4.12. output</a></li>
<li><a href="tests.html#sec:XPECT_outputRegEx">14.6.4.13. outputRegEx</a></li>
<li><a href="tests.html#sec:XPECT_calculatedAccessModifier">14.6.4.14. calculatedAccessModifier</a></li>
<li><a href="tests.html#sec:XPECT_spec">14.6.4.15. spec</a></li>
<li><a href="tests.html#sec:XPECT_deadCode">14.6.4.16. deadCode</a></li>
<li><a href="tests.html#sec:XPECT_returnOrThrows">14.6.4.17. returnOrThrows</a></li>
<li><a href="tests.html#sec:XPECT_lint">14.6.4.18. lint</a></li>
<li><a href="tests.html#sec:XPECT_lintFails">14.6.4.19. lintFails</a></li>
</ul>
</li>
<li><a href="tests.html#sec:FIXME_Xpect_modifier">14.6.5. FIXME Xpect modifier</a></li>
<li><a href="tests.html#sec:Expectmatrix_Xpect_Test_Methods">14.6.6. Expectmatrix Xpect tests</a></li>
<li><a href="tests.html#xpect-lint-tests">14.6.7. Xpect Lint Tests</a></li>
</ul>
</li>
<li><a href="tests.html#xpect-proposal-tests">14.7. Xpect Proposal Tests</a>
<ul class="sectlevel3">
<li><a href="tests.html#sec:Validation_vs__Non_Validation">14.7.1. Validation vs. Non-Validation</a></li>
<li><a href="tests.html#sec:General_Proposal_Test_Features">14.7.2. General Proposal Test Features</a>
<ul class="sectlevel4">
<li><a href="tests.html#sec:Test_Variables">14.7.2.1. Test Variables</a></li>
<li><a href="tests.html#sec:Location_and_Selection">14.7.2.2. at – Location and Selection</a></li>
<li><a href="tests.html#sec:Multi_Line_Expectations_in_Proposal_Tests">14.7.2.3. Multi Line Expectations in Proposal Tests</a></li>
<li><a href="tests.html#sec:Timeout">14.7.2.4. Timeout and Performance</a></li>
</ul>
</li>
<li><a href="tests.html#proposals-verify-existence-of-proposals">14.7.3. proposals – Verify Existence of Proposals</a></li>
<li><a href="tests.html#sec:Verify_displayed_string">14.7.4. display – Verify displayed string</a></li>
<li><a href="tests.html#sec:Apply_Proposal">14.7.5. apply – Apply Proposal</a>
<ul class="sectlevel4">
<li><a href="tests.html#resource-application-in-other-files">14.7.5.1. resource – application in other files</a></li>
</ul>
</li>
<li><a href="tests.html#sec:Content_Assist_Cycling">14.7.6. kind – Content Assist Cycling</a></li>
<li><a href="tests.html#fileValidVerify-validation-status">14.7.7. fileValid – Verify validation status</a></li>
</ul>
</li>
<li><a href="tests.html#sec:Apply_Proposal_And_Execute_Tests">14.8. Apply Proposal And Execute Tests</a></li>
<li><a href="tests.html#sec:Organize_Imports_Test">14.9. Organize Imports Test</a>
<ul class="sectlevel3">
<li><a href="tests.html#organizeimports">14.9.1. organizeImports</a></li>
</ul>
</li>
<li><a href="tests.html#sec:Access_Control_Test">14.10. Access Control Test</a>
<ul class="sectlevel3">
<li><a href="tests.html#test-scenarios">14.10.1. Test Scenarios</a></li>
<li><a href="tests.html#n4js-code-generator">14.10.2. N4JS Code Generator</a></li>
<li><a href="tests.html#xtext-issue-matcher">14.10.3. Xtext Issue Matcher</a></li>
</ul>
</li>
<li><a href="tests.html#sec:Smoke_Tests">14.11. Smoke Tests</a>
<ul class="sectlevel3">
<li><a href="tests.html#how-to-handle-smoke-test-errors">14.11.1. How to handle smoke test errors?</a></li>
<li><a href="tests.html#smoketester-and-exceptionanalyzer">14.11.2. SmokeTester and ExceptionAnalyzer</a></li>
</ul>
</li>
<li><a href="tests.html#sec:UI_Tests_with_SWTBot">14.12. UI Tests with SWTBot</a>
<ul class="sectlevel3">
<li><a href="tests.html#writing-swtbot-tests">14.12.1. Writing SWTBot Tests</a></li>
<li><a href="tests.html#running-swtbot-tests">14.12.2. Running SWTBot Tests</a></li>
</ul>
</li>
<li><a href="tests.html#sec:Debugging_UI_Tests">14.13. Debugging UI Tests</a>
<ul class="sectlevel3">
<li><a href="tests.html#sec:Connecting_to_the_X_server_on_the_build_node">14.13.1. Connecting to the X-server on the build-node</a></li>
<li><a href="tests.html#sec:Tools_to_investigate_the_java_stack">14.13.2. Tools to investigate the java-stack</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#_ui-concepts">15. UI Concepts</a>
<ul class="sectlevel2">
<li><a href="#sec:User_Interface_Concepts">15.1. User Interface Concepts</a>
<ul class="sectlevel3">
<li><a href="#sec:Eclipse_UI_Concepts">15.1.1. Eclipse UI Concepts</a>
<ul class="sectlevel4">
<li><a href="#sec:Label_Provider">15.1.1.1. Label Provider</a></li>
<li><a href="#sec:Markers">15.1.1.2. Markers</a></li>
<li><a href="#sec:Commands__Toolbar_and_Menus">15.1.1.3. Commands, Toolbar and Menus</a></li>
<li><a href="#sec:Content_Assist">15.1.1.4. Content Assist</a></li>
<li><a href="#sec:Quick_Fixes">15.1.1.5. Quick Fixes</a></li>
<li><a href="#sec:Quick_Assist">15.1.1.6. Quick Assist</a></li>
<li><a href="#sec:Clean_Up_Actions">15.1.1.7. Clean Up Actions</a></li>
<li><a href="#sec:Save_Actions">15.1.1.8. Save Actions</a></li>
<li><a href="#sec:Auto_Edit">15.1.1.9. Auto Edit</a></li>
<li><a href="#sec:Template_Proposals">15.1.1.10. Template Proposals</a></li>
<li><a href="#sec:Outline_View___Quick_Outline">15.1.1.11. Outline View / Quick Outline</a></li>
<li><a href="#sec:Navigator__Package_Explorer__Project_Explorer">15.1.1.12. Navigator, Package Explorer, Project Explorer</a></li>
<li><a href="#sec:Hyperlinking_and_Navigation">15.1.1.13. Hyperlinking and Navigation</a></li>
<li><a href="#sec:Syntax_and_Semantic_Coloring">15.1.1.14. Syntax and Semantic Coloring</a></li>
<li><a href="#sec:Code_Formatter">15.1.1.15. Code Formatter</a></li>
<li><a href="#sec:Wizards">15.1.1.16. Wizards</a></li>
<li><a href="#sec:Cheat_Sheets">15.1.1.17. Cheat Sheets</a></li>
<li><a href="#sec:Context_sensitive_Help">15.1.1.18. Context-sensitive Help</a></li>
<li><a href="#sec:Hovers">15.1.1.19. Hovers</a></li>
<li><a href="#sec:Folding">15.1.1.20. Folding</a></li>
<li><a href="#sec:Customizable_validation___severity">15.1.1.21. Customizable validation / severity</a></li>
<li><a href="#sec:Proposals">15.1.1.22. Proposals</a></li>
</ul>
</li>
<li><a href="#sec:Non_Eclipse_UI_Concepts">15.1.2. Non-Eclipse UI Concepts</a>
<ul class="sectlevel4">
<li><a href="#sec:Overlays">15.1.2.1. Overlays</a></li>
<li><a href="#sec:Goto__Inferred__Type">15.1.2.2. Goto (Inferred) Type</a></li>
<li><a href="#sec:Postfix_Completion">15.1.2.3. Postfix Completion</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#_user-interface-resources">15.2. User Interface Resources</a>
<ul class="sectlevel3">
<li><a href="#_icons">15.2.1. Icons</a>
<ul class="sectlevel4">
<li><a href="#_eclipse-platform-icons">15.2.1.1. Eclipse Platform Icons</a></li>
<li><a href="#_n4js-specific-icons">15.2.1.2. N4JS Specific Icons</a></li>
<li><a href="#_high-resolution-icons">15.2.1.3. High Resolution Icons</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="formatting.html#_formatting">16. Formatting</a>
<ul class="sectlevel2">
<li><a href="formatting.html#sec:FmtObjective">16.1. Objective</a>
<ul class="sectlevel3">
<li><a href="formatting.html#sec:FmtFormatting_Comments">16.1.1. Formatting Comments</a></li>
</ul>
</li>
<li><a href="formatting.html#sec:FmtArchitecture">16.2. Architecture</a>
<ul class="sectlevel3">
<li><a href="formatting.html#sec:Implementation_example">16.2.1. Implementation example</a></li>
</ul>
</li>
<li><a href="formatting.html#sec:FmtFormatter_Implementation_Guidelines">16.3. Formatter Implementation Guidelines</a></li>
<li><a href="formatting.html#sec:FmtConfiguration">16.4. Configuration</a></li>
<li><a href="formatting.html#sec:FmtUI_Integration">16.5. UI Integration</a></li>
<li><a href="formatting.html#sec:FmtUnit_Testing_with_Xpect">16.6. Unit Testing with Xpect</a></li>
</ul>
</li>
<li><a href="external_libraries.html#_external-libraries">17. External Libraries</a>
<ul class="sectlevel2">
<li><a href="external_libraries.html#sec:Major_Components">17.1. Major Components</a>
<ul class="sectlevel3">
<li><a href="external_libraries.html#subsec:External_Resources">17.1.1. External Resources</a></li>
<li><a href="external_libraries.html#subsec:External_Library_Workspace">17.1.2. External Library Workspace</a></li>
<li><a href="external_libraries.html#subsec:External_Library_Preference_Store">17.1.3. External Library Preference Store</a></li>
<li><a href="external_libraries.html#subsec:npm_Manager">17.1.4. Library Manager</a></li>
<li><a href="external_libraries.html#subsec:External_Library_Builder_Helper">17.1.5. External Library Builder</a></li>
<li><a href="external_libraries.html#subsec:External_Library_Xtext_Index_Persister">17.1.6. External Library Xtext Index Persister</a></li>
<li><a href="external_libraries.html#subsec:External_Library_Preference_Page">17.1.7. External Library Preference Page</a></li>
</ul>
</li>
<li><a href="external_libraries.html#sec:Headless_External_Library_Support">17.2. Headless External Library Support</a>
<ul class="sectlevel3">
<li><a href="external_libraries.html#_custom-npm-settings">17.2.1. Custom npm settings</a></li>
</ul>
</li>
<li><a href="external_libraries.html#sec:lmFutureWork">17.3. Future Work</a>
<ul class="sectlevel3">
<li><a href="external_libraries.html#subsec:lmMultipleDependencyScope">17.3.1. Multiple Dependency Scope</a></li>
<li><a href="external_libraries.html#subsec:lmRunTestsFromLibrary">17.3.2. Run Tests from TestLibrary</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="json_support.html#sec:JSON_Support">18. JSON Support</a>
<ul class="sectlevel2">
<li><a href="json_support.html#sec:JSON_Parser">18.1. JSON Parser</a>
<ul class="sectlevel3">
<li><a href="json_support.html#sec:JSON_Parser_Unicode_Escaping">18.1.1. Escaping Unicode Control Characters in String Literals</a></li>
<li><a href="json_support.html#sec:JSON_Parser_Empty_Text">18.1.2. Empty Text</a></li>
<li><a href="json_support.html#sec:JSON_Parser_Nested_Structures">18.1.3. Nested Structures</a></li>
<li><a href="json_support.html#sec:JSON_Parser_Whitespace">18.1.4. Whitespace</a></li>
<li><a href="json_support.html#sec:JSON_Parser_Comments">18.1.5. Comments</a></li>
</ul>
</li>
<li><a href="json_support.html#sec:JSON_Language_Extensions">18.2. JSON Language Extensions</a>
<ul class="sectlevel3">
<li><a href="json_support.html#sec:JSON_Validator_Extensions">18.2.1. JSON Validator Extensions</a>
<ul class="sectlevel4">
<li><a href="json_support.html#sec:File_Specitic_Validator_Extensions">18.2.1.1. File-Specific Validator Extensions</a></li>
<li><a href="json_support.html#sec:JSON_Declarative_JSON_Validator_Extensions">18.2.1.2. Declarative JSON Validator Extensions</a></li>
</ul>
</li>
<li><a href="json_support.html#_json-resource-description-strategy">18.2.2. JSON Resource Description Strategy</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="jsdoc.html#_jsdoc">19. JSDoc</a>
<ul class="sectlevel2">
<li><a href="jsdoc.html#sec:Design_Rationale">19.1. Design Rationale</a>
<ul class="sectlevel3">
<li><a href="jsdoc.html#_general-design">19.1.1. General Design</a></li>
<li><a href="jsdoc.html#sec:Type_Expressions">19.1.2. Type Expressions</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="docexporter.html#_docexporter">20. DocExporter</a>
<ul class="sectlevel2">
<li><a href="docexporter.html#sec:Specification_Exporter">20.1. Specification Exporter</a></li>
</ul>
</li>
<li><a href="rename_refactoring.html#_rename-refactoring">21. Rename Refactoring</a>
<ul class="sectlevel2">
<li><a href="rename_refactoring.html#_rename-refactoring-ui-interaction">21.1. Rename Refactoring UI interaction</a></li>
<li><a href="rename_refactoring.html#_renameelementprocessor-interaction">21.2. RenameElementProcessor interaction</a></li>
</ul>
</li>
<li><a href="flow_graphs.html#chap:flowgraphs">22. Flow Graphs</a>
<ul class="sectlevel2">
<li><a href="flow_graphs.html#sec:flowgraphs_overview">22.1. Flow graphs overview</a>
<ul class="sectlevel3">
<li><a href="flow_graphs.html#_internal-graph">22.1.1. Internal graph</a></li>
<li><a href="flow_graphs.html#_optimizations">22.1.2. Optimizations</a></li>
<li><a href="flow_graphs.html#_api-for-client-analyses">22.1.3. API for client analyses</a>
<ul class="sectlevel4">
<li><a href="flow_graphs.html#_mapping-from-internal-to-ast-elements">22.1.3.1. Mapping from internal to AST elements</a></li>
<li><a href="flow_graphs.html#_graph-visitor">22.1.3.2. Graph visitor</a></li>
<li><a href="flow_graphs.html#_graph-explorer">22.1.3.3. Graph explorer</a></li>
<li><a href="flow_graphs.html#_branch-walker">22.1.3.4. Branch walker</a></li>
<li><a href="flow_graphs.html#_example-1-compute-string-for-each-path">22.1.3.5. Example 1: Compute string for each path</a></li>
<li><a href="flow_graphs.html#_path-quantor">22.1.3.6. Path quantor</a></li>
</ul>
</li>
<li><a href="flow_graphs.html#_control-flow-analyses">22.1.4. Control flow analyses</a>
<ul class="sectlevel4">
<li><a href="flow_graphs.html#_dead-code-analysis">22.1.4.1. Dead code analysis</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="flow_graphs.html#sec:dataflow">22.2. Dataflow</a>
<ul class="sectlevel3">
<li><a href="flow_graphs.html#_dataflow-graph">22.2.1. Dataflow graph</a></li>
<li><a href="flow_graphs.html#_dataflow-analyses">22.2.2. Dataflow analyses</a>
<ul class="sectlevel4">
<li><a href="flow_graphs.html#_def-def-def-nothing-analysis">22.2.2.1. Def&#8594;Def / Def&#8594;Nothing analysis</a></li>
<li><a href="flow_graphs.html#_def-use-decl-analysis">22.2.2.2. Def|Use&#8592;Decl analysis</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="publish_npms.html#sec:publish-npms-to-public">23. Publish npms</a>
<ul class="sectlevel2">
<li><a href="publish_npms.html#sec:publish-npms-n4js-maven">23.1. Publish n4js-libs to during  maven build</a></li>
</ul>
</li>
<li><a href="appendix_a_hints.html#sec:Hints">Appendix A: Hints</a>
<ul class="sectlevel2">
<li><a href="appendix_a_hints.html#sec:XtextInjection">A.1. Xtext Injection</a>
<ul class="sectlevel3">
<li><a href="appendix_a_hints.html#sec:DI_MultipleInjectors_Singletons">A.1.1. Multiple Injectors and Singletons</a>
<ul class="sectlevel4">
<li><a href="appendix_a_hints.html#sec:DI_avoid_duplicate_singletons">A.1.1.1. Avoiding duplicate singletons</a>
<ul class="sectlevel5">
<li><a href="appendix_a_hints.html#sec:DI_binding_in_shared">A.1.1.1.1. Defining binding in the shared injector</a></li>
<li><a href="appendix_a_hints.html#sec:DI_binding_in_custom">A.1.1.1.2. Defining binding in the custom injector</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="appendix_a_hints.html#sec:DI_Hints">A.1.2. Dependency Injection Hints</a>
<ul class="sectlevel4">
<li><a href="appendix_a_hints.html#sec:DI_custom_bundle">A.1.2.1. Use DI in custom bundle, use DI with extensions</a>
<ul class="sectlevel5">
<li><a href="appendix_a_hints.html#sec:DI_custom_bundle_problem">A.1.2.1.1. Problem</a></li>
<li><a href="appendix_a_hints.html#sec:DI_custom_bundle_solution">A.1.2.1.2. Solution</a></li>
</ul>
</li>
<li><a href="appendix_a_hints.html#sec:Access_Other_DSL_Injector">A.1.2.2. How do I get the Guice Injector of my language?</a>
<ul class="sectlevel5">
<li><a href="appendix_a_hints.html#sec:DSL_Injector_UI_context">A.1.2.2.1. UI context</a></li>
<li><a href="appendix_a_hints.html#sec:DSL_Injector_Non_UI_context">A.1.2.2.2. Non UI context but with injection context</a></li>
<li><a href="appendix_a_hints.html#sec:DSL_Injector_Non_UI_non_injection_context">A.1.2.2.3. Non UI context without injection context</a></li>
</ul>
</li>
<li><a href="appendix_a_hints.html#sec:Cancel_Indicator">A.1.2.3. How do I get cancel indicators in different contexts?</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="appendix_a_hints.html#sec:Eclipse">A.2. Eclipse</a>
<ul class="sectlevel3">
<li><a href="appendix_a_hints.html#sec:Show_Xtext_Index">A.2.1. Show the current Xtext index</a></li>
<li><a href="appendix_a_hints.html#sec:Plugin_spy">A.2.2. Plug-in spy</a></li>
</ul>
</li>
<li><a href="appendix_a_hints.html#sec:Maven-hints">A.3. Maven</a>
<ul class="sectlevel3">
<li><a href="appendix_a_hints.html#how-to-check-for-maven-mojo-updates">A.3.1. How to check for Maven MOJO updates</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#_module-loading">Appendix B: Module Loading</a>
<ul class="sectlevel2">
<li><a href="appendix_b_module_loading.html#sec:Dependency_Management">B.1. Dependency Management</a></li>
<li><a href="appendix_b_module_loading.html#ecmascript-modules">B.2. ECMAScript Modules</a>
<ul class="sectlevel3">
<li><a href="appendix_b_module_loading.html#sec:ES5_Modules_Systems">B.2.1. ES5 Modules Systems</a></li>
<li><a href="appendix_b_module_loading.html#sec:ES6_Modules">B.2.2. ES6 Modules</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#sec:ECMAScript_Module_Loaders">B.3. ECMAScript Module Loaders</a>
<ul class="sectlevel3">
<li><a href="appendix_b_module_loading.html#sec:ES6_Module_Loaders">B.3.1. ES6 Module Loaders</a></li>
<li><a href="appendix_b_module_loading.html#sec:Polyfills_for_ES6_Module_Loaders">B.3.2. Polyfills for ES6 Module Loaders</a>
<ul class="sectlevel4">
<li><a href="appendix_b_module_loading.html#sec:es6_module_loader">B.3.2.1. es6-module-loader</a></li>
<li><a href="appendix_b_module_loading.html#sec:SystemJS">B.3.2.2. SystemJS</a></li>
<li><a href="appendix_b_module_loading.html#sec:Demo">B.3.2.3. Demo</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#case-study-typescript">B.4. Case Study : TypeScript</a>
<ul class="sectlevel3">
<li><a href="appendix_b_module_loading.html#sec:ES6_Modules_Support">B.4.1. ES6 Modules Support</a></li>
<li><a href="appendix_b_module_loading.html#sec:TypeScript_and_Module_Loading">B.4.2. TypeScript and Module Loading</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#sec:Cyclic_Dependencies">B.5. Cyclic Dependencies</a>
<ul class="sectlevel3">
<li><a href="appendix_b_module_loading.html#sec:Setup">B.5.1. Setup</a></li>
<li><a href="appendix_b_module_loading.html#sec:Transpile_and_Execute">B.5.2. Transpile and Execute</a>
<ul class="sectlevel4">
<li><a href="appendix_b_module_loading.html#sec:Module_Format___AMD">B.5.2.1. Module Format = AMD</a></li>
<li><a href="appendix_b_module_loading.html#sec:Module_Format___CommonJS">B.5.2.2. Module Format = CommonJS</a></li>
<li><a href="appendix_b_module_loading.html#sec:Module_Format___SystemJS">B.5.2.3. Module Format = SystemJS</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#sec:Conclusion">B.5.3. Conclusion</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#system.register-as-transpilation-target">B.6. System.register as transpilation target</a>
<ul class="sectlevel3">
<li><a href="appendix_b_module_loading.html#sec:Introduction">B.6.1. Introduction</a>
<ul class="sectlevel4">
<li><a href="appendix_b_module_loading.html#sec:External_Transpilers">B.6.1.1. External Transpilers</a></li>
<li><a href="appendix_b_module_loading.html#sec:Example_of_a_System_register_module">B.6.1.2. Example of a System.register module</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#sec:Structure_of_a_System_register_module">B.6.2. Structure of a System.register module</a></li>
<li><a href="appendix_b_module_loading.html#_transpilation-hints">B.6.3. Transpilation Hints</a>
<ul class="sectlevel4">
<li><a href="appendix_b_module_loading.html#sec:Handling_Imports">B.6.3.1. Handling Imports</a></li>
<li><a href="appendix_b_module_loading.html#sec:__exportFn__">B.6.3.2. &lt;&lt;exportFn&gt;&gt;</a></li>
<li><a href="appendix_b_module_loading.html#sec:Handling_Exports">B.6.3.3. Handling Exports</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#sec:Examples_w__Circular_Dependencies">B.6.4. Examples w/ Circular Dependencies</a></li>
<li><a href="appendix_b_module_loading.html#sec:N4JS_Examples_w__Circular_Dependencies">B.6.5. N4JS Examples w/ Circular Dependencies</a>
<ul class="sectlevel4">
<li><a href="appendix_b_module_loading.html#sec:Unresolved_Cyclic_Dependencies">B.6.5.1. Unresolved Cyclic Dependencies</a></li>
<li><a href="appendix_b_module_loading.html#sec:Variables___Functions">B.6.5.2. Examples with Variables &amp; Functions</a></li>
<li><a href="appendix_b_module_loading.html#sec:Classes">B.6.5.3. Examples with Classes</a></li>
<li><a href="appendix_b_module_loading.html#sec:Examples_with_SubClassing">B.6.5.4. Examples with SubClassing</a></li>
<li><a href="appendix_b_module_loading.html#sec:Miscellaneous">B.6.5.5. Miscellaneous</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#_resources">B.6.6. Resources</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#sec:CommonJS_as_transpilation_target">B.7. CommonJS as transpilation target</a>
<ul class="sectlevel3">
<li><a href="appendix_b_module_loading.html#_introduction-2">B.7.1. Introduction</a></li>
<li><a href="appendix_b_module_loading.html#sec:Transpilation_Hints">B.7.2. Transpilation Hints</a>
<ul class="sectlevel4">
<li><a href="appendix_b_module_loading.html#sec:Import_Statements">B.7.2.1. Import Statements</a></li>
<li><a href="appendix_b_module_loading.html#sec:Export_Statements">B.7.2.2. Export Statements</a></li>
<li><a href="appendix_b_module_loading.html#sec:Tracking_Live_Bindings">B.7.2.3. Tracking Live Bindings</a></li>
<li><a href="appendix_b_module_loading.html#sec:A_complete_example">B.7.2.4. A complete example</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#_resources-2">B.7.3. Resources</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="appendix_c_license.html#sec:License">Appendix C: License</a></li>
<li><a href="appendix_d_acronyms.html#sec:Acronyms">Appendix D: Acronyms</a></li>
<li><a href="appendix_e_bibliography_and_footnotes.html#_bibliography-and-footnotes">Appendix E: Bibliography and Footnotes</a></li>
</ul>
</div>
</div>
<div id="content"><div class="sect1">
<h2 id="_ui-concepts"><a class="anchor" href="#_ui-concepts"></a><a class="link" href="#_ui-concepts">15. UI Concepts</a></h2>
<div class="sectionbody">
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title=""></i>
</td>
<td class="content">
Parts of this chapter may be outdated.
</td>
</tr>
</table>
</div>
<div class="sect2 language-n4js">
<h3 id="sec:User_Interface_Concepts"><a class="anchor" href="#sec:User_Interface_Concepts"></a><a class="link" href="#sec:User_Interface_Concepts">15.1. User Interface Concepts</a></h3>
<div class="sect3">
<h4 id="sec:Eclipse_UI_Concepts"><a class="anchor" href="#sec:Eclipse_UI_Concepts"></a><a class="link" href="#sec:Eclipse_UI_Concepts">15.1.1. Eclipse UI Concepts</a></h4>
<div class="paragraph">
<p>The following list gives an overview of Eclipse specific UI concepts and which classes are used for implementation.</p>
</div>
<div class="sect4">
<h5 id="sec:Label_Provider"><a class="anchor" href="#sec:Label_Provider"></a><a class="link" href="#sec:Label_Provider">15.1.1.1. Label Provider</a></h5>
<div class="paragraph">
<p>Also provides decorations for icons and text labels.</p>
</div>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
Example
</td>
<td class="hdlist2">
<p>The representation of objects in the outline view or in search results.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Eclipse API
</td>
<td class="hdlist2">
<div class="ulist">
<ul>
<li>
<p><code>o.e.jface.viewers.ILabelProvider</code> → without styes</p>
</li>
<li>
<p><code>o.e.jface.viewers.DelegatingStyledCellLabelProvider.IStyledLabelProvider</code> → with styles Drawback: Depends on Image rather than ImageDescriptor (see below)</p>
</li>
</ul>
</div>
</td>
</tr>
<tr>
<td class="hdlist1">
Xtext Specifics
</td>
<td class="hdlist2">
<div class="ulist">
<ul>
<li>
<p><code>Declarative API</code>  via reflective, polymorphic dispatching. <code>org.eclipse.xtext.ui.label.AbstractLabelProvider</code></p>
</li>
<li>
<p>Allows to work with ImageDescriptors (non-ui-thread, can be composed), but cumbersome</p>
</li>
<li>
<p>DefaultLabelProvider will be used everywhere (outline etc.), returns the <code>name</code>  (via reflection). You could bind specific label providers.</p>
</li>
<li>
<p>DescriptionLabelProvider provides labels for objects from the Xtext index used by <code>open model element</code> , <code>find references</code>  – the later is already customized)</p>
</li>
</ul>
</div>
</td>
</tr>
<tr>
<td class="hdlist1">
Best Practices
</td>
<td class="hdlist2">
<p>Labels are often use-case specific, so a single label provider is not always useful Therefore, in Xtext are different label providers for different use cases. Use cases are defined and enumerated (see <code>DefaultUiModule.configure*Label*</code>).
+
Often labels could be easier created where they are needed instead of using a label provider (even for things like OutlineView). (LabelProvider are maybe over-engineered). (Note: default label provider has dependencies to SWT, because it uses images, which are often not needed; also they are only called with an object and no further configuration).
+
Images:
+</p>
<div class="ulist">
<ul>
<li>
<p>DeclarativeLabelProvider: text and image (String: path relative to icons folder; or: ImageDescriptor, or Image), put it into folder (needs to be called <code>icons</code> , otherwise bind another name)</p>
</li>
<li>
<p>better use AbstractLabelProvider and use EMF concepts (easier to debug and handle)</p>
</li>
<li>
<p>image format and size: sub-folders with 32, 12, 16, 24, etc. (look which sizes are needed); in about view maybe bigger; png (supports transparency)</p>
</li>
</ul>
</div>
</td>
</tr>
</table>
</div>
</div>
<div class="sect4">
<h5 id="sec:Markers"><a class="anchor" href="#sec:Markers"></a><a class="link" href="#sec:Markers">15.1.1.2. Markers</a></h5>
<div class="quoteblock">
<blockquote>
<div class="paragraph">
<p>Markers are objects that may be associated with Workbench resources. There are many uses of markers in the Workbench&#8230;&#8203;
Markers are shown in a marker view (Tasks, Problems or Bookmark view) or on the marker bar in the editor area.</p>
</div>
</blockquote>
<div class="attribution">
&#8212; Eclispe Help
</div>
</div>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
Examples
</td>
<td class="hdlist2">
<p>Tasks, Problems, Bookmarks, Breakpoints, Trace information</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Eclipse API
</td>
<td class="hdlist2">
<p><code>org.eclipse.core.resources.IMarker</code> and <code>IResource.findMarkers</code>
+</p>
<div class="ulist">
<ul>
<li>
<p>Marker types registered via extension point (basically String). A marker is more or less a Map of String &#8594; String with some meta information, e.g. the resource location in WS, line numbers, type</p>
</li>
<li>
<p>Markers are very efficient (e.g., find markers of a certain type), cf Xtext Specifics</p>
</li>
<li>
<p>For validation, some new marker types are already registered.</p>
</li>
</ul>
</div>
</td>
</tr>
<tr>
<td class="hdlist1">
Xtext
</td>
<td class="hdlist2">
<p>(2.6)
+</p>
<div class="ulist">
<ul>
<li>
<p>Todo-Markers are created during build, task list is populated by these markers.</p>
</li>
<li>
<p><code>org.eclipse.xtext.tasks.ITaskFinder</code> (and default implementation is bound by default, can be replaced with custom implementation)</p>
</li>
</ul>
</div>
</td>
</tr>
<tr>
<td class="hdlist1">
Best Practices
</td>
<td class="hdlist2">
<p>In Xtend, markers are used to trace from original file to generated file. They are hidden (and not displayed), so in general markers can be used for non-UI-problems as well (but only available in Eclipse of course) clean up markers: no general solution, often managed by some (single) life-cycle aware class (e.g., Builder)</p>
</td>
</tr>
</table>
</div>
</div>
<div class="sect4">
<h5 id="sec:Commands__Toolbar_and_Menus"><a class="anchor" href="#sec:Commands__Toolbar_and_Menus"></a><a class="link" href="#sec:Commands__Toolbar_and_Menus">15.1.1.3. Commands, Toolbar and Menus</a></h5>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
Examples
</td>
<td class="hdlist2">
<p>Organize Imports,</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Eclipse API
</td>
<td class="hdlist2">
<p>use Commands + Handlers instead of Actions (or ActionDelegates etc.)</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Xtext Specifics
</td>
<td class="hdlist2">
<p>uses commands and handlers</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Best Practice
</td>
<td class="hdlist2">
<p><strong>Use commands and handlers</strong> -
handler usually only delegates to real thing (that is, retrieve parameters from context and call the real thing)<br>
<strong>Register in pluginxml</strong> via ExecutableExtensionFactory to be able to use injection (also pre-generatd, e.g.:</p>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">            &lt;handler class="org.eclipse.n4js.ui.N4JSExecutableExtensionFactory:org.eclipse.xtext.ui.editor.handler.ValidateActionHandler"
                          commandId="org.eclipse.n4js.N4JS.validate"&gt;</code></pre>
</div>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p><strong>Undo</strong>: use TextEdit and MultiTextEdit (composed)<br>
otherwise very low level</p>
</div>
</div>
<div class="sect4">
<h5 id="sec:Content_Assist"><a class="anchor" href="#sec:Content_Assist"></a><a class="link" href="#sec:Content_Assist">15.1.1.4. Content Assist</a></h5>
<div class="quoteblock">
<blockquote>
<div class="paragraph">
<p>Content assist allows you to provide context sensitive content completion upon user request. Popup windows (infopops) are used to propose possible text choices to complete a phrase. The user can select these choices for insertion in the text. Content assist also supports contextual infopops for providing the user with information that is related to the current position in the document.</p>
</div>
</blockquote>
<div class="attribution">
&#8212; Eclipse Help
</div>
</div>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
Risk
</td>
<td class="hdlist2">
<p>Always needs longer than anticipated.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Examples
</td>
<td class="hdlist2">
<p>complete name of function in function call, complete keywords</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Eclipse API
</td>
<td class="hdlist2">
<div class="ulist">
<ul>
<li>
<p>IContentAssistant wraps the widget,</p>
</li>
<li>
<p>IContentProposalProvider computes the (array of) CompletionProposal (quite cumbersome!).</p>
</li>
<li>
<p>Many extension interfaces that provide valuable UI features.</p>
</li>
</ul>
</div>
</td>
</tr>
<tr>
<td class="hdlist1">
Xtext Specifics
</td>
<td class="hdlist2">
<div class="ulist">
<ul>
<li>
<p>ConfigurableCompletionProposal implements the currently defined extension interfaces, provides getters to modify the proposal after the fact.</p>
</li>
<li>
<p>Context: The ContentAssistContext is provided by the framework according to the current cursor position in the document (cf. <code>ContentAssisParser</code>), semantic context (semantic element) computed with best match strategy (worst case you get the root element). Multiple contexts may be valid at the very same cursor position since the replace region may be different for different proposals.</p>
</li>
<li>
<p>Various abstracts above the JFace stuff are available in Xtext, some of the <code>over the top</code> , others quite handy.</p>
</li>
</ul>
</div>
</td>
</tr>
<tr>
<td class="hdlist1">
Best Practices
</td>
<td class="hdlist2">
<div class="ulist">
<ul>
<li>
<p>List of follow elements can be supposed to be complete, no need to figure out them with regular expressions etc.</p>
</li>
<li>
<p>in rare cases it is necessary to <code>manually</code>  scan the text context, e.g. to get the variable name based on the variable type. → we will provider a utility class for that using regex. NEVER search on the text with simple string methods.</p>
</li>
<li>
<p>In N4JSProposalProvider, override pre-generated methods (see <code>AbstractN4JSProposalProvider</code>) – do not overload (with concrete semantic element)</p>
</li>
<li>
<p>how to implement complete-methods:</p>
<div class="ulist">
<ul>
<li>
<p>inspect context, examine current semantic element provide elements from scope or hard coded proposal: see <a href="#sec:Proposals">Proposals</a></p>
</li>
</ul>
</div>
</li>
</ul>
</div>
</td>
</tr>
</table>
</div>
</div>
<div class="sect4">
<h5 id="sec:Quick_Fixes"><a class="anchor" href="#sec:Quick_Fixes"></a><a class="link" href="#sec:Quick_Fixes">15.1.1.5. Quick Fixes</a></h5>
<div class="quoteblock">
<blockquote>
Users can select a problem marker and choose a Quick Fix from a popup containing the list of supplied fixes contributed for the marker.
</blockquote>
<div class="attribution">
&#8212; Eclipse Help
</div>
</div>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
Examples
</td>
<td class="hdlist2">
<p>Add Import, Add Override Annotation</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Eclipse API
</td>
<td class="hdlist2">
<p>Based on ICompletionProposal (powerful)
+</p>
<div class="ulist">
<ul>
<li>
<p>QuickFixes are registered to marker (marker attribute: is fixable or not – this attribute is a guess only, there does not need to be a quick fix)</p>
</li>
<li>
<p>MarkerResolutionGenerator (can also be used to fix several markers at once)</p>
</li>
</ul>
</div>
</td>
</tr>
<tr>
<td class="hdlist1">
Xtext Specifics
</td>
<td class="hdlist2">
<p>Based on ISematicModification (seemingly powerful but in fact weak) and IModification (less weak, but still very weak compared to ICompletionProposal) – only creates DocumentChanges.
+
Declarativ API that links to issue codes via annotations on 'fix' methods in AbstractDeclarativeQuickfixProvider.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Best Practices
</td>
<td class="hdlist2">
<p>ICompletionProposal vs. DocumentChanges, ICompletionProposal is much more powerful. IModifications can also provide semantic changes, but not really recommended
+</p>
<div class="ulist">
<ul>
<li>
<p>Associated to isses via IssueCodes, @Fix similar to @Check API – only less powerful Xtext abstraction (no ICompletionProposal)</p>
</li>
<li>
<p>use issue data to provide hints for fix labels (which should be fast!) or solution strategies (but only strings) → do not compute the label for the fix from the model!</p>
</li>
<li>
<p>share code between checks and fixes → no built-in pattern, come up with utility methods (maybe define conventions)</p>
</li>
<li>
<p>maybe Sebastian can add a solution that more information is available via @Fix-approach</p>
</li>
<li>
<p>no order of quickfixes (sorted by name and priority, latter is not provided by default)</p>
</li>
<li>
<p>there can be several @Fix for a single issue code, or pass arbitrary number of resolution to the acceptor</p>
</li>
<li>
<p>for most cases simple Xtext quick fix api is good enough (e.g. all Xtend quick fixes use that)
+
→ Xtext feature request: solve multiple markers at a time (possible to do that right now: bind custom <code>XtextQuickAssistProcessor</code>, override <code>MarkerResolutionGenerator.getAdaptedResolutions(List&lt;IssueResolution&gt;</code>) – return a WorkbenchMarkerResolution)</p>
</li>
</ul>
</div>
</td>
</tr>
</table>
</div>
</div>
<div class="sect4">
<h5 id="sec:Quick_Assist"><a class="anchor" href="#sec:Quick_Assist"></a><a class="link" href="#sec:Quick_Assist">15.1.1.6. Quick Assist</a></h5>
<div class="quoteblock">
<blockquote>
"Quick assists perform local code transformations. They are invoked on a selection or a single cursor in the Java editor and use the same shortcut as quick fixes (Ctrl+1), but quick assist are usually hidden when an error is around. To show them even with errors present on the same line, press Ctrl+1 a second time."  (Eclipse Help)
</blockquote>
</div>
<div class="paragraph">
<p><code>like a quickfix without a problem</code></p>
</div>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
Examples
</td>
<td class="hdlist2">
<p>Add/remove inferred types</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Eclipse API
</td>
<td class="hdlist2">
<p>Takes cursor position</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Xtext
</td>
<td class="hdlist2">
<p>no Xtext support, e.g. no default implementation (XtextQuickAssistProcessor is a quick fix provider, has nothing to do with QuickAssist) but: XtextQuickAssistProcessor, override canAssist, override computeQuickAssistProposals</p>
</td>
</tr>
</table>
</div>
</div>
<div class="sect4">
<h5 id="sec:Clean_Up_Actions"><a class="anchor" href="#sec:Clean_Up_Actions"></a><a class="link" href="#sec:Clean_Up_Actions">15.1.1.7. Clean Up Actions</a></h5>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
Examples
</td>
<td class="hdlist2">
<p>Remove unused local vars, sort members</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Eclipse API
</td>
<td class="hdlist2">
<p>None, JDT specific (see ICleanUp)</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Xtext Specifics
</td>
<td class="hdlist2">
<p>None</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Best Practice
</td>
<td class="hdlist2">
<p>Monkey sees - Monkey does (look at JDT), In the end a it’s a CompositeRefactoring, which is a CompletionProposal</p>
</td>
</tr>
</table>
</div>
</div>
<div class="sect4">
<h5 id="sec:Save_Actions"><a class="anchor" href="#sec:Save_Actions"></a><a class="link" href="#sec:Save_Actions">15.1.1.8. Save Actions</a></h5>
<div class="paragraph">
<p>Similar to clean up actions but performed on save</p>
</div>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
Examples
</td>
<td class="hdlist2">
<p>Format on save, Organize imports on save</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Eclipse API
</td>
<td class="hdlist2">
<p>None, JDT specific (see IPostSaveListener)</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Xtext Specifics
</td>
<td class="hdlist2">
<p>None</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Best Practice
</td>
<td class="hdlist2">
<p>XtextDocumentProvider.doSaveDocument (maybe better solutions in the future ;-) )</p>
</td>
</tr>
</table>
</div>
</div>
<div class="sect4">
<h5 id="sec:Auto_Edit"><a class="anchor" href="#sec:Auto_Edit"></a><a class="link" href="#sec:Auto_Edit">15.1.1.9. Auto Edit</a></h5>
<div class="paragraph">
<p>Auto edit is about closing braces that just have been typed, adding indentation after a line break the code snippet <code>if (true)</code> so basically it should be unobtrusive typing aids.</p>
</div>
<div class="paragraph">
<p>By default, restore model structure when editing (guide the user to proper text formatting, help the parser). Should not be used for other purposes in order to not hinder the user’s flow of editing.</p>
</div>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
Examples
</td>
<td class="hdlist2">
<p>( &#8594; ( &lt;cursor&gt; )</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Eclipse API
</td>
<td class="hdlist2">
<p>org.eclipse.jface.text.IAutoEditStrategy</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Xtext Specifics
</td>
<td class="hdlist2">
<p>org.eclipse.xtext.ui.editor.autoedit.AbstractEditStrategy, some utility methods + implements VerifyKeyListener. May use the ISourceViewer via implements ISourceViewerAware</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Best Practices
</td>
<td class="hdlist2">
<p>Keep it as it is.</p>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Fun example but not useful in practice cf. <a href="https://code.google.com/a/eclipselabs.org/p/xtext-forms-integration/source/browse/trunk/plugins/org.eclipse.xtext.example.domainmodel.ui/src/org/eclipse/xtext/example/ui/autoedit/FantasticAutoEditStrategy.java?r=19">FantasticAutoEditStrategy</a></p>
</div>
</div>
<div class="sect4">
<h5 id="sec:Template_Proposals"><a class="anchor" href="#sec:Template_Proposals"></a><a class="link" href="#sec:Template_Proposals">15.1.1.10. Template Proposals</a></h5>
<div class="paragraph">
<p>More sophisticated edit utils that are invoked by means of content assist.</p>
</div>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
Examples
</td>
<td class="hdlist2">
<p>sysout &#8594; System.out.println(<code>&lt;cursor&gt;</code> );</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Eclipse API
</td>
<td class="hdlist2">
<p>Part of the completion proposal API, e.g. ICompletionProposal</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Xtext Specifics
</td>
<td class="hdlist2">
<p>org.eclipse.xtext.ui.editor.contentassist.ITemplateProposalProvider, template contexts along the grammar rules by default, need to be stripped down to become usable.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Best Practice
</td>
<td class="hdlist2">
<p>ship some: create them manually in workbench, export them as XML, fix XML file (add IDs, in Xtext documentation), put XML file in folder <code>templates</code>  in UI plugin where propose a certain proposal: customize XtextTemplateContextTypeRegistry (bind subclass, override register context types) – by default too many context types are registered placeholders inside templates specific to Xtext – RTFM</p>
</td>
</tr>
</table>
</div>
</div>
<div class="sect4">
<h5 id="sec:Outline_View___Quick_Outline"><a class="anchor" href="#sec:Outline_View___Quick_Outline"></a><a class="link" href="#sec:Outline_View___Quick_Outline">15.1.1.11. Outline View / Quick Outline</a></h5>
<div class="paragraph">
<p>Structural represenation of the file contents (usually with different filter and sorting strategies).</p>
</div>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
Examples
</td>
<td class="hdlist2">
<p>Outline View (but not Navigator nor package explorer), Quick Outline (in Xtext: same provider)</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Eclipse API
</td>
<td class="hdlist2">
<p>org.eclipse.ui.views.contentoutline.IContentOutlinePage</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Xtext Specifics
</td>
<td class="hdlist2">
<p>Lazy tree creation, syncing via EObject ranges, thread save access to the EObject from nodes. Declarative API to create the tree contents. org.eclipse.xtext.ui.editor.outline.impl.DefaultOutlineTreeProvider
+
allow actions on outline nodes (e.g., goto referenced file in <code>import</code>  of outline)</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Best Practice
</td>
<td class="hdlist2">
<div class="ulist">
<ul>
<li>
<p>Produced from semantic model, tree structure of outline nodes</p>
<div class="ulist">
<ul>
<li>
<p>show tree based on TypeModel, maybe filter out elements w/o SyntaxElements (with type model, this should be rather cheap!)</p>
</li>
<li>
<p>use icons and styled labels (first user impression!)</p>
</li>
</ul>
</div>
</li>
<li>
<p>May run in the background (BackgroundOutlineTreeProvider)</p>
</li>
<li>
<p>done lazily</p>
</li>
<li>
<p>workflow: reconceiler: outline is a model listener</p>
</li>
</ul>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Helpful tools for icons in outline view:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="http://marketplace.eclipse.org/content/eclipse-icon-archive-tool">Eclipse view</a> to show available Eclipse icons (that are of course licenced under EPL) with possibility to export them (<a href="http://bwgz-org.googlecode.com/files/EclipseIconArchiveTool-1.pdf">documentation</a>)</p>
</li>
<li>
<p>overview of Eclipse icons: <a href="http://eclipse-icons.i24.cc/" class="bare">http://eclipse-icons.i24.cc/</a></p>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="sec:Navigator__Package_Explorer__Project_Explorer"><a class="anchor" href="#sec:Navigator__Package_Explorer__Project_Explorer"></a><a class="link" href="#sec:Navigator__Package_Explorer__Project_Explorer">15.1.1.12. Navigator, Package Explorer, Project Explorer</a></h5>
<div class="paragraph">
<p>three <code>explorers</code> , Navigator <code>latest</code>  and most extensible one</p>
</div>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
Best Practices
</td>
<td class="hdlist2">
<p>use Navigator only! (RTFM, nothing specific to Xtext yet)</p>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>cf. <a href="http://projects.eclipse.org/projects/technology.handly" class="bare">http://projects.eclipse.org/projects/technology.handly</a> <code>read index and show it in the navigator</code></p>
</div>
</div>
<div class="sect4">
<h5 id="sec:Hyperlinking_and_Navigation"><a class="anchor" href="#sec:Hyperlinking_and_Navigation"></a><a class="link" href="#sec:Hyperlinking_and_Navigation">15.1.1.13. Hyperlinking and Navigation</a></h5>
<div class="paragraph">
<p>Linking (propose multiple linking targets, e.g. goto declaration or goto implementation when CTRL (or other modifier) + Left Mouse Click on method when receiver type is interface - show all available implementations)</p>
</div>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
Examples
</td>
<td class="hdlist2">
<p>Go to declaration, Go to implementation, Go to super</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Eclipse API
</td>
<td class="hdlist2">
<p>org.eclipse.jface.text.hyperlink.IHyperlinkDetector</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Xtext Specifics
</td>
<td class="hdlist2">
<p>org.eclipse.xtext.ui.editor.hyperlinking.DefaultHyperlinkDetector, navigation to EObject URI most interesting: SIGNIFICANT cf. org.eclipse.xtext.resource.ILocationInFileProviderExtension.RegionDescription</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Best Practice
</td>
<td class="hdlist2">
<div class="ulist">
<ul>
<li>
<p>subclass and bind IHyperlinkHelper (returns an array of possible links, first one is the default)</p>
</li>
<li>
<p>also see ILocationInFileProviderExtension (cf. navigation to syntax elements instead of types)</p>
</li>
</ul>
</div>
</td>
</tr>
</table>
</div>
</div>
<div class="sect4">
<h5 id="sec:Syntax_and_Semantic_Coloring"><a class="anchor" href="#sec:Syntax_and_Semantic_Coloring"></a><a class="link" href="#sec:Syntax_and_Semantic_Coloring">15.1.1.14. Syntax and Semantic Coloring</a></h5>
<div class="paragraph">
<p>Coloring based on the lexical tokens or based on the semantic tokens (the parsed model). The parser may treat certain lexical keywords as valid identifiers in some contexts. Some of those should not appear as keywords. Semantic coloring is usually more expensive to compute thus run in the background and with some delay</p>
</div>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
Examples
</td>
<td class="hdlist2">
<p>Numbers, String literals (lexical) Escape sequences in Strings, method calls, property read / write access (semantic)</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Eclipse API
</td>
<td class="hdlist2">
<p><code>org.eclipse.jface.text.presentation.IPresentationDamager</code> <code>org.eclipse.jface.text.presentation.IPresentationRepairer</code> <code>org.eclipse.jface.text.rules.ITokenScanner</code>
+
Scan for tokens and associate text attributes with tokens. Compute the region of the document that has to be recolored after a text change. Tokens may not overlap.
+
Also Eclipse provides Themes that are styled via CSS. Coloring can be adjusted to themes where the logical names are mapped to different default values.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Xtext Specifics
</td>
<td class="hdlist2">
<div class="ulist">
<ul>
<li>
<p><code>o.e.x.ui.editor.syntaxcoloring.ITextAttributeProvider</code> - associate Antlr token names with coloring styles (logical names of text coloring)</p>
</li>
<li>
<p><code>o.e.x.ui.editor.syntaxcoloring.AbstractAntlrTokenToAttributeIdMapper</code>- convert the antlr tokens to JFace ITokens with proper text applied</p>
</li>
<li>
<p><code>o.e.x.ui.editor.syntaxcoloring.IHighlightingConfiguration</code> - register logical text colorings with default values, yields a preference page and the proper configuration for the text attribute provider</p>
</li>
<li>
<p><code>o.e.x.ui.editor.syntaxcoloring.ISemanticHighlightingCalculator</code> - traverse the AST and associate arbitrary ranges of the text with.</p>
</li>
<li>
<p>logical coloring names (this is a key to a style stored in the preference store), if multiple styles are returned, styles will be merged if they overlap (and if possible); JFace constraints are implicitly fulfilled</p>
</li>
</ul>
</div>
</td>
</tr>
<tr>
<td class="hdlist1">
Best Practice
</td>
<td class="hdlist2">
<div class="ulist">
<ul>
<li>
<p>subclass DefaultSemanticHighlightingCalculator and bind ISemanticHighlightingCalculator</p>
<div class="ulist">
<ul>
<li>
<p>traverse resource from left to right (usually order of semantic elements – small performance improvement)</p>
</li>
</ul>
</div>
</li>
<li>
<p>provide new logical style: subclass DefaultHighlightingConfiguration and bind IHighlightingConfiguration; override configure (see overridden)</p>
</li>
<li>
<p>semantic coloring always wins</p>
</li>
<li>
<p>only a few decisions can me made in lexical coloring, override lexical:</p>
<div class="ulist">
<ul>
<li>
<p>subclass <code>DefaultAntlrTokenToAttributeIdMapper</code> bind <code>TokenTypeToStringMapper</code></p>
</li>
<li>
<p>e.g., color jsdoc comments differently to multiline, regex</p>
</li>
<li>
<p>e.g. color tags inside jsdocs or regex inside, use semantic coloring</p>
</li>
<li>
<p>lexical: different kind of keywords (e.g., N4JS keywords vs. JS keywords)</p>
</li>
</ul>
</div>
</li>
<li>
<p>change coloring (via toggle button), possible approach:</p>
<div class="ulist">
<ul>
<li>
<p>(inject singleton into highlighter, state of singleton is changed by toggle button, listen to that object in the editor, calculator cannot be triggered from outside due to UI-thread issues)</p>
</li>
<li>
<p>prefered: store state in preference store and get the information then from there in the hightligher, inject PreferencestoreAccess in Calculator</p>
</li>
</ul>
</div>
</li>
</ul>
</div>
</td>
</tr>
</table>
</div>
</div>
<div class="sect4">
<h5 id="sec:Code_Formatter"><a class="anchor" href="#sec:Code_Formatter"></a><a class="link" href="#sec:Code_Formatter">15.1.1.15. Code Formatter</a></h5>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
Examples
</td>
<td class="hdlist2">
<p>Auto-Format Source Code, Auto-Format code inserted by code-rewrite</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Eclipse API
</td>
<td class="hdlist2">
<p><code>org.eclipse.jface.text.formatter.IContentFormatter</code> - here is the document and some range - modify at will</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Xtext Specifics
</td>
<td class="hdlist2">
<p>Declarative Formatting API (to be deprecated) - associate formatting rules with grammar elements New formatting API (mixture of declarative and imperative) - here is the model, do what you want (space before, linebreak after, indentation increase / decrease), the engine will merge your advices and apply them to the document</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Best Practice
</td>
<td class="hdlist2">
<p>wait for 2.8 (maybe in 2.7.x)</p>
</td>
</tr>
</table>
</div>
</div>
<div class="sect4">
<h5 id="sec:Wizards"><a class="anchor" href="#sec:Wizards"></a><a class="link" href="#sec:Wizards">15.1.1.16. Wizards</a></h5>
<div class="quoteblock">
<blockquote>
Wizards are used to guide the user through a sequenced set of tasks. Your plug-in can contribute wizards at predefined extension points in the workbench. It can also create and launch its own wizards.
</blockquote>
<div class="attribution">
&#8212; Eclipse Help
</div>
</div>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
Examples
</td>
<td class="hdlist2">
<p>New N4JS Class</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Eclipse API
<br>
Xtext Specifics
</td>
<td class="hdlist2">
<div class="ulist">
<ul>
<li>
<p>Xtend based Wizards</p>
</li>
<li>
<p>also see Formular Editor for Embedded Xtext editor</p>
</li>
</ul>
</div>
</td>
</tr>
<tr>
<td class="hdlist1">
Best Practices
</td>
<td class="hdlist2">
<div class="ulist">
<ul>
<li>
<p>use preferences (could be hidden, so use them even if not made configurable to the user)</p>
</li>
<li>
<p>use standard JFace wizard API, use Xtend template expressions for file templates</p>
</li>
</ul>
</div>
</td>
</tr>
</table>
</div>
</div>
<div class="sect4">
<h5 id="sec:Cheat_Sheets"><a class="anchor" href="#sec:Cheat_Sheets"></a><a class="link" href="#sec:Cheat_Sheets">15.1.1.17. Cheat Sheets</a></h5>
<div class="quoteblock">
<blockquote>
<div class="paragraph">
<p>Composite cheat sheets provide guidance through complex problems by breaking the problem into a set of smaller tasks. Composite cheat sheets are registered using the the <code>org.eclipse.ui.cheatsheets.cheatSheetContent</code> extension point.</p>
</div>
</blockquote>
<div class="attribution">
&#8212; Eclipse Help
</div>
</div>
<div class="paragraph">
<p>(In Scala IDE: Work Sheets), often combined with Code Snippets</p>
</div>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
Examples
</td>
<td class="hdlist2">
<p>Create Hello World Application</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Eclipse API
<br>
Xtext Specifics
</td>
<td class="hdlist2">
<p>None, probably the embedded editor could be used in a REPL (Read-Evaluate-Print-Loop)</p>
</td>
</tr>
</table>
</div>
</div>
<div class="sect4">
<h5 id="sec:Context_sensitive_Help"><a class="anchor" href="#sec:Context_sensitive_Help"></a><a class="link" href="#sec:Context_sensitive_Help">15.1.1.18. Context-sensitive Help</a></h5>
<div class="quoteblock">
<blockquote>
<div class="paragraph">
<p>A focused set of help topics that is related to the current context can be shown to users on demand using context-sensitive help. This form of user assistance is delivered to users when a platform-specific trigger is activated (e.g. F1 key on Windows, Ctrl+F1 on GTK, Help key on Carbon). Until Eclipse 3.1, context-sensitive help was presented in infopop windows. Since 3.1, a new Help view is the preferred way to deliver context-sensitive information to the user.</p>
</div>
</blockquote>
<div class="attribution">
&#8212; Eclipse Help
</div>
</div>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
Examples
</td>
<td class="hdlist2">
<p>Help in Formular Editor, Help about syntax construct, API-Help</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Eclipse API
<br>
Xtext Specifics
</td>
<td class="hdlist2">
<p>None</p>
</td>
</tr>
</table>
</div>
</div>
<div class="sect4">
<h5 id="sec:Hovers"><a class="anchor" href="#sec:Hovers"></a><a class="link" href="#sec:Hovers">15.1.1.19. Hovers</a></h5>
<div class="paragraph">
<p>Hover allow to display additional information as soon as the cursor stays on a certain text region. Some hovers can be requested by shortcuts (e.g. F2) similar to sort of an online help.</p>
</div>
<div class="paragraph">
<p>Different kind of hovers may appear depending on the context, e.g. the error hover will have higher prio than the documentation hover. Different modifier keys may be assigned to request different hover kinds while hovering a region with the mouse. (didn’t a proper code pointer, though)</p>
</div>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
Examples
</td>
<td class="hdlist2">
<p>Hover over method shows JSDoc, Signatures or inferred types, error / problem details</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Eclipse API
</td>
<td class="hdlist2">
<p><code>org.eclipse.jface.text.ITextHover</code> + <code>ITextHoverExtension*</code> - compute hover based on the region that is hovered. Various indirections with <code>IInformationControl</code> and <code>IInformationControlCreator</code> with many extension interfaces</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Xtext Specifics
</td>
<td class="hdlist2">
<p><code>org.eclipse.xtext.ui.editor.hover.IEObjectHover</code> - compute hover based on <code>EObjects</code></p>
</td>
</tr>
<tr>
<td class="hdlist1">
Best Practice
</td>
<td class="hdlist2">
<p>see XBase hover stuff</p>
</td>
</tr>
</table>
</div>
</div>
<div class="sect4">
<h5 id="sec:Folding"><a class="anchor" href="#sec:Folding"></a><a class="link" href="#sec:Folding">15.1.1.20. Folding</a></h5>
<div class="paragraph">
<p>Code folding allows to skip parts of the code that are mandatory semantically but usually do not provide added value for the reader, e.g. import sections</p>
</div>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
Examples
</td>
<td class="hdlist2">
<p>Import section folding, folding of arbitrary methods or comments</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Eclipse API
</td>
<td class="hdlist2">
<p>Not much there, most of that stuff is implemented specific to JDT or ODE. Projections usually only work per line, that is, a subsection of a line cannot be folded, e.g. it’s not possible to show</p>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>var x = new Map&lt;String, List&lt;Pair&lt;String, Number&gt;&gt;&gt;()</code></pre>
</div>
</div>
<div class="paragraph">
<p>as</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>var x = new Map&lt;...&gt;()</code></pre>
</div>
</div>
<div class="paragraph">
<p>Line only limitation in SWT (a guess, didn’t work for Sebastian otherwise)</p>
</div>
</td>
</tr>
<tr>
<td class="hdlist1">
Xtext Specifics
</td>
<td class="hdlist2">
<div class="ulist">
<ul>
<li>
<p><code>org.eclipse.xtext.ui.editor.folding.DefaultFoldingRegionProvider</code> - here is the resource, compute the folding</p>
</li>
<li>
<p><code>org.eclipse.xtext.ui.editor.folding.DefaultFoldingStructureProvider</code> - bridge between editor and custom computation, preferences etc would be read from here</p>
</li>
<li>
<p>no preference page for folding provided by Xtext</p>
</li>
</ul>
</div>
</td>
</tr>
<tr>
<td class="hdlist1">
Best Practice
</td>
<td class="hdlist2">
<div class="ulist">
<ul>
<li>
<p>maybe limit to blocks (subclass default, bind to interface)</p>
</li>
<li>
<p>probably provide your own folding preference page</p>
</li>
</ul>
</div>
</td>
</tr>
</table>
</div>
</div>
<div class="sect4">
<h5 id="sec:Customizable_validation___severity"><a class="anchor" href="#sec:Customizable_validation___severity"></a><a class="link" href="#sec:Customizable_validation___severity">15.1.1.21. Customizable validation / severity</a></h5>
<div class="paragraph">
<p>Some problems are more important to the user than others so they want to change the severity.</p>
</div>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
Examples
</td>
<td class="hdlist2">
<p>Deprecation could be an error, warning or ignored (e.g. in test projects)</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Eclipse API
</td>
<td class="hdlist2">
<p>None</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Xtext Specifics
</td>
<td class="hdlist2">
<p>IssueSeverityProvider (since 2.6), Monkey sees monkey does: see subclasses of IssueSeverityProvider (we already do that)</p>
</td>
</tr>
</table>
</div>
</div>
<div class="sect4">
<h5 id="sec:Proposals"><a class="anchor" href="#sec:Proposals"></a><a class="link" href="#sec:Proposals">15.1.1.22. Proposals</a></h5>
<div class="paragraph">
<p>Created by Content Assist, Quick Fixes, Quick Assist.</p>
</div>
<div class="paragraph">
<p>Basics</p>
</div>
<div class="ulist">
<ul>
<li>
<p>simplest case: proposals are strings to be inserted</p>
</li>
<li>
<p>or displayed string is different from inserted one (e.g. FQN vs. simple)</p>
</li>
<li>
<p>ConfigurableCompletionProposal created via factory methods in AbstractN4JSProposalProvider (*create*Pro)</p>
</li>
<li>
<p>PrefixMatcher (by default CamelCase aware) – for filtering, it usually is not necessary to use it when computing the proposal (only if it expensive to compute proposals) – that is, prefix can be ignored when computing a proposal because the prefix matcher will filter out invalid proposals anyway</p>
</li>
<li>
<p>pass a filter (Guava preodicate) to filter out (semantically invalid) proposals, cf. lookupCrossReference(..) – for the things where there are proposals created by default</p>
</li>
<li>
<p>priority defined by an int – for sorting. Cf. ContentProposalPriorities → define default priorities (constant values) in N4JS, do not add some random integers!</p>
</li>
<li>
<p>modes: bind RepeatedContentAssistProcessor and enable modeaware in ProposalProvider (e.g. for private members which require a quickfix)</p>
</li>
<li>
<p>what could be done in the background: hover, lazy (not prepared) proposals (cf. JDT), Xtext 2.7.; different situations are processed in parallel</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Several changes (e.g. automatic import):</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>ConfigurableCompletionProposal.setTextApplier</code></p>
</li>
<li>
<p>TextApplier: can open dialogs etc., TextApplier is the callback</p>
</li>
<li>
<p>usual case: add text at cursor position and somewhere else:</p>
<div class="ulist">
<ul>
<li>
<p>get document in TextApplier</p>
</li>
<li>
<p>for performance, but also: do not use semantic changes in content assist, because model is broken (you will get funny things) – use model (AST) to get offset, but then insert line breaks etc. → maybe create utility class for retrieving current formattings which are then used in the text edit → maybe provide tools for retrieving certain locations (e.g. import section, field section, etc.)</p>
</li>
<li>
<p>do not create model (AST) fragments (which are then serialized), instead directly provide text</p>
</li>
<li>
<p>use TextEdit and MultiTextEdit</p>
</li>
<li>
<p>set TextViewer redraw to false and to true after the text edits were applied</p>
</li>
<li>
<p>have proper TESTS to ensure that file is not broken after the changes</p>
</li>
</ul>
</div>
</li>
<li>
<p><strong>LinkedEditing</strong>:</p>
<div class="ulist">
<ul>
<li>
<p>Linked-Editing mode in ConfigurableCompletionProposal with one editing group only (basically: move the cursor somewhere after editing it, see setSimpleLinkedMode)</p>
</li>
<li>
<p>do it manually: cf. LinkedPositionGroup (see call hierarchy of constructor) – used for quick fixes or refactorings rather for content assist</p>
</li>
</ul>
</div>
</li>
</ul>
</div>
</div>
</div>
<div class="sect3">
<h4 id="sec:Non_Eclipse_UI_Concepts"><a class="anchor" href="#sec:Non_Eclipse_UI_Concepts"></a><a class="link" href="#sec:Non_Eclipse_UI_Concepts">15.1.2. Non-Eclipse UI Concepts</a></h4>
<div class="paragraph">
<p>The following entries are not necessarily implemented yet.</p>
</div>
<div class="sect4">
<h5 id="sec:Overlays"><a class="anchor" href="#sec:Overlays"></a><a class="link" href="#sec:Overlays">15.1.2.1. Overlays</a></h5>
<div class="paragraph">
<p>An overlay is a small annotation similar to an hover, attached to a specific location in the editor and is moved with that location.</p>
</div>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
Examples
</td>
<td class="hdlist2">
<p>Show inferred types</p>
</td>
</tr>
</table>
</div>
</div>
<div class="sect4">
<h5 id="sec:Goto__Inferred__Type"><a class="anchor" href="#sec:Goto__Inferred__Type"></a><a class="link" href="#sec:Goto__Inferred__Type">15.1.2.2. Goto (Inferred) Type</a></h5>
<div class="paragraph">
<p>Navigate to an inferred type (or other <code>invisible</code>  information)</p>
</div>
</div>
<div class="sect4">
<h5 id="sec:Postfix_Completion"><a class="anchor" href="#sec:Postfix_Completion"></a><a class="link" href="#sec:Postfix_Completion">15.1.2.3. Postfix Completion</a></h5>
<div class="paragraph">
<p>(IntelliJ) Replace code <em>AFTER</em> an expression</p>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_user-interface-resources"><a class="anchor" href="#_user-interface-resources"></a><a class="link" href="#_user-interface-resources">15.2. User Interface Resources</a></h3>
<div class="sect3">
<h4 id="_icons"><a class="anchor" href="#_icons"></a><a class="link" href="#_icons">15.2.1. Icons</a></h4>
<div class="paragraph">
<p>In parts, the N4JS IDE re-uses some of the icons that come with the Eclipse Platform as well as the Eclipse JDT development environment. However, in some cases we also provide our own icons to illustrate N4JS-specific concepts.</p>
</div>
<div class="sect4">
<h5 id="_eclipse-platform-icons"><a class="anchor" href="#_eclipse-platform-icons"></a><a class="link" href="#_eclipse-platform-icons">15.2.1.1. Eclipse Platform Icons</a></h5>
<div class="paragraph">
<p>When re-using the Eclipse Platform Icons, the icons are usually copied over to the <code>icons/</code> folder of the <code>org.eclipse.n4js.ui</code> bundle. In this folder, the <code>README.adoc</code> file keeps book on the origin of all the collected icons (e.g. different Eclipse Projects).</p>
</div>
</div>
<div class="sect4">
<h5 id="_n4js-specific-icons"><a class="anchor" href="#_n4js-specific-icons"></a><a class="link" href="#_n4js-specific-icons">15.2.1.2. N4JS Specific Icons</a></h5>
<div class="paragraph">
<p>In some cases, the icons the Eclipse eco-system provides do not suffice to sensibly express N4JS concepts. In these cases we provide our own icons. When designing those we try to imitate the general Eclipse artstyle in order for our icons to integrate well with the overall appearance of Eclipse.</p>
</div>
<div class="paragraph">
<p>For the creation of new icons, the <code>eclipse-svg-icons</code> repository (see <a href="https://github.com/Seung-Yoon/eclipse-svg-icons" class="bare">https://github.com/Seung-Yoon/eclipse-svg-icons</a>) has proven helpful. The repository contains raw SVG files which can be used to reproduce the bitmap icons that are contained in, for instance, the <code>org.eclipse.platform.ui</code> or <code>org.eclipse.jdt.ui</code> bundle. Based on that, common vector-graphics editing software may be used to further adapt color, form and style of existing icons (e.g. Inkscape <a href="https://inkscape.org/en/" class="bare">https://inkscape.org/en/</a>).</p>
</div>
</div>
<div class="sect4">
<h5 id="_high-resolution-icons"><a class="anchor" href="#_high-resolution-icons"></a><a class="link" href="#_high-resolution-icons">15.2.1.3. High Resolution Icons</a></h5>
<div class="paragraph">
<p>With the Neon release, Eclipse SWT introduced explicit support for high-DPI monitors (see <a href="https://www.eclipse.org/eclipse/news/4.6/platform.php#swt-autoscale" class="bare">https://www.eclipse.org/eclipse/news/4.6/platform.php#swt-autoscale</a>). In order to provide a good user experience, we want to provide high-DPI support for as many of our icons as possible. For that, it suffices to simply provide an alternative resource with higher resolution by appending the prefix @2x to its name (e.g. <code>class.png</code> and <code>class@2x.png</code>). Code-wise, no adjustments are required. In case of copied Eclipse Platform Icons, most of the time a corresponding 2x-version can be obtained from the original source. In case of N4JS Specific Icons, we export all icons in the resolutions 16x16 and 32x32. For that, it is of particular importance to make sure that the scaling is done in accordance with the native resolution (cf. pixel perfect scaling, also see <a href="https://en.wikipedia.org/wiki/Native_resolution" class="bare">https://en.wikipedia.org/wiki/Native_resolution</a>).</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Version 0.9<br>
Last updated 2019-08-08 13:15:33 CEST
</div>
</div>
<!-- ************* docinfo-footer *************************************************************** -->
<div class="Grid social" style="color:#d5dfea">
  <div class="Cell Cell--2-12 m-Cell--withMargin">
    <h2>Quick Links</h2>
    <ul>
      <li><a href="../downloads.html">Download</a></li>
      <li><a href="../userguides/index.html">Documentation</a></li>
      <li><a href="https://github.com/eclipse/n4js/">Source</a></li>
      <li><a href="https://github.com/eclipse/n4js/issues">Issues</a></li>
    </ul>
  </div>
  <div class="Cell Cell--2-12 m-Cell--withMargin">
    <br/><br/>
    <ul>
      <li><a href="https://www.eclipse.org/forums/index.php/f/365/">Forum</a></li>
      <li><a href="http://n4js.blogspot.de/">Blog</a></li>
      <li><a href="https://dev.eclipse.org/mailman/listinfo/n4js-dev">Mailing List</a></li>
      <li><a href="https://projects.eclipse.org/projects/technology.n4js">Eclipse Project Page</a></li>
      <li><a href="https://twitter.com/n4jsdev">Tweets by n4jsdev</a></li>
    </ul>
  </div>
  <div class="Cell Cell--2-12 m-Cell--withMargin">
    <br/><br/>
    <ul>
      <li><a href="http://www.eclipse.org/">Eclipse Home</a></li>
      <li><a href="http://www.eclipse.org/legal/privacy.php">Privacy Policy</a></li>
      <li><a href="http://www.eclipse.org/legal/termsofuse.php">Terms of Use</a></li>
      <li><a href="http://www.eclipse.org/legal/copyright.php">Copyright Agent</a></li>
      <li><a href="http://www.eclipse.org/legal/">Legal</a></li>
    </ul>
  </div>
  <div style="clear: both; height: 0; overflow: hidden;"></div>
</div>

<!-- ************* UI Scripts ************* -->
<script type="text/javascript" src="scripts/back-to-top.js"></script>

<script type="text/javascript" src="scripts/treeview.js"></script>
<script type="text/javascript" src="scripts/toc.js"></script>

<!-- ************* Prism.js Syntax Highlighting ************* -->
<script src="scripts/prism.js"></script>

<script type="text/javascript">
	// Add the 'toclist' id for search function
	$(".toc2 > ul").attr('id', 'toclist');
	// Generate a Search input form
	$("#toclist > li:first-of-type").before('<input type="text" id="pagesearch" onkeyup="search()" placeholder="Search for section...">');
	$("#toclist > li:first-of-type").before('<i id="clear" class="fa fa-times-circle-o"></i>');
	$("#clear").click(function(){
	    $("#pagesearch").val('');
	    search();
	    $('.toc2 > ul').treeView('collapseAll');
	});
	// intialize Treeview.js
	$(".toc2 > ul").treeView();
	// Initialize Scrollspy
</script>
<!-- ************* docinfo-footer *************************************************************** -->
</body>
</html>